Docs: improve docs narrative around "ENSNode Plugins", "ENSDb Writers", and "ENSDb Readers".#2227
Merged
Merged
Conversation
…-examples-content
New pages for ENSDb Writers, ENSDb Readers, and ENSNode Plugins. Update relevant links.
…iter-reader-ensnode-plugins
|
Contributor
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughAdds three integration concepts—ENSDb Writers, ENSDb Readers, ENSNode Plugins—by creating dedicated docs pages, updating the Integration Options index and Starlight sidebar, repositioning ENSIndexer as an ENSDb Writer reference implementation, and aligning cross-document links, glossary entries, and hosted-instances plugin links. ChangesENSDb & ENSNode Plugins Architecture
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related PRs
Suggested labelsdocs Poem
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Contributor
Greptile SummaryThis PR improves the documentation narrative around three key architectural concepts: ENSNode Plugins, ENSDb Writers, and ENSDb Readers. It restructures the ENSDb service docs (flattening the Usage and Integrations sections), adds new dedicated pages for each concept under the Integrate section, and updates all glossary definitions to reflect the new, more abstract terminology — replacing ENSIndexer-specific terms like "ENSIndexer Schema" with the implementation-agnostic "ENSDb Writer Schema".
Confidence Score: 5/5Documentation-only changes with well-formed redirects and consistent terminology updates throughout; safe to merge. All changes are documentation content and sidebar configuration. The five new redirect rules correctly cover removed and renamed pages. The terminology migration from ENSIndexer-specific terms to the implementation-agnostic ENSDb Writer/ENSDb Reader vocabulary is applied consistently across all modified files. The only finding is a cosmetic rendering issue (raw HTML in a string prop) that does not affect navigation, correctness, or build integrity. docs/ensnode.io/src/content/docs/docs/services/ensdb/integrations.mdx has a display-only issue with an HTML tag in a LinkCard description string. Important Files Changed
Flowchart%%{init: {'theme': 'neutral'}}%%
flowchart TD
NP["ENSNode Plugin\n(abstract spec)"]
EW["ENSDb Writer\nimplements plugins + metadata writer"]
EM["ENSDb Metadata Writer\nwrites metadata to ENSNode Schema"]
ER["ENSDb Reader\nreads indexed data + metadata"]
EDB[("ENSDb Instance\nPostgreSQL")]
EWS["ENSDb Writer Schema\nindexed ENS data"]
ENS["ENSNode Schema\noperational metadata"]
NP -->|"implemented by"| EW
EW -->|"includes"| EM
EW -->|"writes indexed data to"| EWS
EM -->|"writes metadata to"| ENS
EWS -->|"lives in"| EDB
ENS -->|"lives in"| EDB
ER -->|"reads from"| EDB
style NP fill:#e8f4fd,stroke:#2980b9
style EW fill:#eafaf1,stroke:#27ae60
style ER fill:#fef9e7,stroke:#f39c12
Reviews (18): Last reviewed commit: "Fix typo" | Re-trigger Greptile |
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Pull request overview
This PR refines the documentation narrative around ENSNode Plugins, ENSDb Writers, and ENSDb Readers, positioning ENSIndexer/ENSApi explicitly as reference implementations and adding dedicated integration-option pages to explain the architecture and interoperability model.
Changes:
- Reframes ENSIndexer docs to describe it as an ENSDb Writer reference implementation and clarifies how it implements ENSNode Plugins.
- Expands the ENSDb glossary with definitions for ENSNode Plugin and ENSDb Metadata Writer, and updates related metadata terminology.
- Adds new integration-option pages for ENSDb Writers, ENSDb Readers, and ENSNode Plugins, and links them from the integration options index + sidebar.
Reviewed changes
Copilot reviewed 14 out of 14 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/ensnode.io/src/content/docs/docs/services/ensindexer/index.mdx | Repositions ENSIndexer as a reference ENSDb Writer and links to glossary terminology. |
| docs/ensnode.io/src/content/docs/docs/services/ensindexer/contributing/creating-a-plugin.mdx | Renames/reframes the page to explain ENSNode Plugins and ENSIndexer’s plugin implementation structure. |
| docs/ensnode.io/src/content/docs/docs/services/ensdb/index.mdx | Updates “What you can build” section to point readers to integration inspirations. |
| docs/ensnode.io/src/content/docs/docs/services/ensdb/concepts/glossary.mdx | Adds/updates key definitions (ENSNode Plugin, ENSDb Writer/Reader, Metadata Writer) and metadata terminology. |
| docs/ensnode.io/src/content/docs/docs/integrate/unigraph/schema-reference.mdx | Updates wording/links to refer to Unigraph as an ENSNode Plugin implemented in ENSIndexer. |
| docs/ensnode.io/src/content/docs/docs/integrate/omnigraph/concepts.mdx | Updates wording/links to refer to Unigraph as an ENSNode Plugin implemented in ENSIndexer. |
| docs/ensnode.io/src/content/docs/docs/integrate/integration-options/index.mdx | Adds new top-level integration options for Writers/Readers/Plugins and renumbers subsequent sections. |
| docs/ensnode.io/src/content/docs/docs/integrate/integration-options/ensnode-plugins.mdx | New page describing the ENSNode Plugin specification and listing core/community plugins. |
| docs/ensnode.io/src/content/docs/docs/integrate/integration-options/ensdb.mdx | Adds paragraph explaining ENSDb’s metadata spec and links to Writers/Readers pages. |
| docs/ensnode.io/src/content/docs/docs/integrate/integration-options/ensdb-writers.mdx | New page describing the ENSDb Writer spec and reference/partner implementations. |
| docs/ensnode.io/src/content/docs/docs/integrate/integration-options/ensdb-readers.mdx | New page describing the ENSDb Reader spec and reference reader apps. |
| docs/ensnode.io/src/content/docs/docs/integrate/ensv2-readiness.mdx | Updates wording/links to refer to Unigraph as an ENSNode Plugin implemented in ENSIndexer. |
| docs/ensnode.io/config/integrations/starlight/sidebar-topics/services.ts | Renames the ENSIndexer contributing sidebar item to “ENSNode Plugins”. |
| docs/ensnode.io/config/integrations/starlight/sidebar-topics/integrate.ts | Adds sidebar entries for Writers/Readers/Plugins integration-option pages. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
![vercel[bot]](https://avatars.githubusercontent.com/in/8329?s=60&v=4){kind=small}
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 7
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In
`@docs/ensnode.io/src/content/docs/docs/integrate/integration-options/ensdb-readers.mdx`:
- Around line 44-47: The LinkCard for "Learn more about ENSAnalytics (coming
soon)" is missing the required href prop; update the LinkCard component in
ensdb-readers.mdx to include an href (e.g., a placeholder route like
"/ensanalytics" or a temporary external URL) so the
`@astrojs/starlight/components` LinkCard receives a valid href, keeping the title
"ENSAnalytics" and description unchanged; ensure the href is a string literal
and points to the placeholder until the real route exists.
In
`@docs/ensnode.io/src/content/docs/docs/integrate/integration-options/ensdb-writers.mdx`:
- Line 11: The bullet under "writer responsibilities" contains a malformed
fragment "How to process onchain data into (including transforming raw onchain
data into a desired internal data model)"; replace it with a complete,
grammatical sentence such as "How to process on‑chain data, including
transforming raw on‑chain data into a desired internal data model" so the
responsibility reads clearly—update the writer responsibilities bullet in the
ENSDB writers section to use that full sentence.
In
`@docs/ensnode.io/src/content/docs/docs/integrate/integration-options/ensdb.mdx`:
- Line 14: Update the interoperability phrasing in the sentence referencing the
"ENSDb standard" so that it reads "...supports decoupling and interop with any
EnsDbReader implementation." Locate the sentence that mentions "EnsDbWriters",
"ENSDb instance" and "EnsDbReaders" and replace the fragment "interop with any
of EnsDbReaders" with "interop with any EnsDbReader implementation" to tighten
grammar and clarity.
In
`@docs/ensnode.io/src/content/docs/docs/integrate/integration-options/ensnode-plugins.mdx`:
- Line 23: In the paragraph starting with "ENSNode Plugins are the key
architectural piece..." replace both occurrences of the phrase "standards
compliant" with the hyphenated form "standards-compliant" to make the compound
adjective consistent and improve readability; update the two instances that
describe an ENSDb Writer producing a "standards-compliant ENSDb" and an ENSDb
Reader being "standards-compliant" so both are hyphenated.
In `@docs/ensnode.io/src/content/docs/docs/services/ensdb/concepts/glossary.mdx`:
- Line 70: Update the glossary sentence for ENSDb Reader to avoid "sole ENSDb
Writer" — in the ENSDb Reader definition replace "the sole [ENSDb
Writer](`#ensdb-writer`)" with either "an [ENSDb Writer](`#ensdb-writer`)" or "the
configured [ENSDb Writer](`#ensdb-writer`) for the reader context" so it aligns
with the multi-tenant model; edit the sentence in the ENSDb Reader paragraph in
glossary.mdx (the line containing "Any application that reads ENS data...")
accordingly.
- Around line 64-65: Update the broken self-link and grammar in the ENSDb
glossary sentence: change the relative link
"docs/services/ensdb/concepts/glossary#ensnode-metadata-table" to an absolute
path by adding a leading "/" (i.e.
"/docs/services/ensdb/concepts/glossary#ensnode-metadata-table") and fix the
agreement typo by replacing "instance that have" with "instance that has" in the
same paragraph referring to ENSIndexer and the ENSNode Metadata Table.
In
`@docs/ensnode.io/src/content/docs/docs/services/ensindexer/contributing/creating-a-plugin.mdx`:
- Around line 11-13: Replace the inconsistent glossary terms in this document:
change occurrences of `EnsDbWriter`, `EnsDbWriters`, and `EnsDbReaders` to the
canonical capitalized forms `ENSDb Writer`, `ENSDb Writers`, and `ENSDb Readers`
respectively so they match the rest of the docs; update both the inline mentions
and any link text (e.g., the two instances in the second paragraph and the first
sentence) while preserving existing links/URLs and surrounding punctuation.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: 17b3bbe3-d245-47a9-85d0-e73061144aee
📒 Files selected for processing (14)
docs/ensnode.io/config/integrations/starlight/sidebar-topics/integrate.tsdocs/ensnode.io/config/integrations/starlight/sidebar-topics/services.tsdocs/ensnode.io/src/content/docs/docs/integrate/ensv2-readiness.mdxdocs/ensnode.io/src/content/docs/docs/integrate/integration-options/ensdb-readers.mdxdocs/ensnode.io/src/content/docs/docs/integrate/integration-options/ensdb-writers.mdxdocs/ensnode.io/src/content/docs/docs/integrate/integration-options/ensdb.mdxdocs/ensnode.io/src/content/docs/docs/integrate/integration-options/ensnode-plugins.mdxdocs/ensnode.io/src/content/docs/docs/integrate/integration-options/index.mdxdocs/ensnode.io/src/content/docs/docs/integrate/omnigraph/concepts.mdxdocs/ensnode.io/src/content/docs/docs/integrate/unigraph/schema-reference.mdxdocs/ensnode.io/src/content/docs/docs/services/ensdb/concepts/glossary.mdxdocs/ensnode.io/src/content/docs/docs/services/ensdb/index.mdxdocs/ensnode.io/src/content/docs/docs/services/ensindexer/contributing/creating-a-plugin.mdxdocs/ensnode.io/src/content/docs/docs/services/ensindexer/index.mdx
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
♻️ Duplicate comments (1)
docs/ensnode.io/src/content/docs/docs/services/ensdb/index.mdx (1)
31-36:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winQualify the lead sentence to match the plugin-scoped section.
The new heading says "Indexed ENS State", but Line 33 still reads as if every ENSDb instance contains the full live ENS state. That contradicts the note immediately below and revives the same completeness claim that was previously called out.
✏️ Suggested edit
- An **ENSDb instance** contains the **live onchain state of ENS**. + An **ENSDb instance** contains the **live onchain state of ENS as indexed by its activated ENSNode plugins**.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/ensnode.io/src/content/docs/docs/services/ensdb/index.mdx` around lines 31 - 36, The lead sentence under the "Indexed ENS State" heading incorrectly asserts completeness; update the sentence that currently reads "An ENSDb instance contains the live onchain state of ENS." to qualify that the instance only contains the portion of the live onchain ENS state indexed by its active plugins (for example: "An ENSDb instance contains the portion of the live onchain ENS state indexed by its active plugins."). Ensure you update the sentence near the "Indexed ENS State" heading so it aligns with the existing plugin-scoped note below.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/ensnode.io/src/content/docs/docs/hosted-instances.mdx`:
- Line 23: Remove the stray thematic break line consisting of `---` that appears
after the exported constants and before the first heading in the MDX page (it's
rendering as an unintended horizontal rule); simply delete that line so the
frontmatter/exported constants flow directly into the page body and no
page-level separator is rendered.
---
Duplicate comments:
In `@docs/ensnode.io/src/content/docs/docs/services/ensdb/index.mdx`:
- Around line 31-36: The lead sentence under the "Indexed ENS State" heading
incorrectly asserts completeness; update the sentence that currently reads "An
ENSDb instance contains the live onchain state of ENS." to qualify that the
instance only contains the portion of the live onchain ENS state indexed by its
active plugins (for example: "An ENSDb instance contains the portion of the live
onchain ENS state indexed by its active plugins."). Ensure you update the
sentence near the "Indexed ENS State" heading so it aligns with the existing
plugin-scoped note below.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: df0eca42-e1fd-4fd9-b392-bd23b1620985
📒 Files selected for processing (7)
docs/ensnode.io/src/content/docs/docs/hosted-instances.mdxdocs/ensnode.io/src/content/docs/docs/integrate/index.mdxdocs/ensnode.io/src/content/docs/docs/integrate/integration-options/ensdb.mdxdocs/ensnode.io/src/content/docs/docs/services/ensdb/concepts/index.mdxdocs/ensnode.io/src/content/docs/docs/services/ensdb/index.mdxdocs/ensnode.io/src/content/docs/docs/services/ensdb/reference-implementation.mdxdocs/ensnode.io/src/content/docs/docs/services/ensindexer/contributing/creating-a-plugin.mdx
Please enter the commit message for your changes. Lines starting
…iter-reader-ensnode-plugins
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 24 out of 24 changed files in this pull request and generated 1 comment.
Comments suppressed due to low confidence (1)
docs/ensnode.io/src/content/docs/docs/services/ensdb/integrations.mdx:4
- This page is routed and linked from the Services sidebar as “Integrations” (
/docs/services/ensdb/integrations), but its frontmattertitleis “Using ENSDb”. That mismatch makes navigation/search/breadcrumbs harder to follow (sidebar says one thing, page H1 says another). Consider aligning the page title with the sidebar label (or vice-versa).
…iter-reader-ensnode-plugins
…iter-reader-ensnode-plugins
…iter-reader-ensnode-plugins
Y3drk
approved these changes
Jun 4, 2026
| | `indexing_metadata_context` | [Indexing metadata context](#indexing-metadata-context) of the [ENSIndexer instance](#ensindexer-instance) | | ||
| | Key | Description | | ||
| | --------------------------- | ------------------------------------------------------------------------------------------------------ | | ||
| | `indexing_metadata_context` | [Indexing metadata context](#indexing-metadata-context) for the [ENSDb Writer](#ensdb-writer) instance | |
Member
There was a problem hiding this comment.
The styles of links inside tables do not match the styling of our "normal" links.
Not sure if that's intentional or not.
The potential fix is out of scope for this PR, so I suggest we do it in a follow-up PR (provided that we want to unify the link styles)
| import HostedInstanceVersionWarning from "@components/molecules/HostedInstanceVersionWarning.astro"; | ||
| import EnsSubgraphCorrectnessPostEnsV2Launch from "@components/molecules/EnsSubgraphCorrectnessPostEnsV2Launch.astro"; | ||
|
|
||
| export const pluginLink = (pluginName) => `<a href="/docs/integrate/integration-options/ensnode-plugins#existing-plugins" class="underline">${pluginName}</a>`; |
Member
There was a problem hiding this comment.
Another good thing to refine in the follow-up PR would be the styling of this link. It doesn't match our other links quite yet (but it's close!!!)
NOTE: The change is out of scope for this PR, so I'd recommend applying the fix in a new one.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Suggested review order
Integration section
Services section
Why
This PR is a followup to PR #2199, and PR #2202, and addresses the "Big Feedback" (point 11. and 17.) section the doc discussed in this thread, as well as the feedback shared in this thread.
More feedback was shared in [this Slack thread(https://namehash.slack.com/archives/C086Z6FNBHN/p1780339533610239) as well and this PR address all the points that were raised in the thread.
This PR also updates the ENSDb glossary around "ENSDb Writer" and "ENSDb Reader" (details about this update were discussed here).
Next steps
Tasks below will be executed in follow up PRs.